供应商模块 API 接口规范

0. 文档结论

• 供应商为资源管理之前的独立一级模块，管理端基址为 /admin/supplier。
• 供应商菜单、页面与按钮由平台配置 supplier:* 权限码；服务端逐接口校验权限并失败关闭，不定义固定本地角色。类型、信用、状态、审批意见和账户证明附件使用独立权限码。
• 本地不提供 approve、reject 或“我的审批待办”；审批人在企业微信处理。转交、加签和同意并加签本期不建模。
• 企业微信 Supplier 模板必须增加申请人、必需审批节点和实际审批人的受控部门字段；外部适配器按 controlId 从表单/详情同步，完整追溯统一保存到单个版本化 detail_snapshot_ciphertext，禁止用当前通讯录补写。
• Gateway 路由与最小权限已在 #6191/#6194 完成并经 TEST 验证。
• 注册主体允许 0..N 个初始账户；没有账户也能完成注册，但不具备付款资格。
• 供应商页面统一使用平台字典并按需加载：供应商类型读取 supplier_type（GET /admin/dict/data/supplier_type），生命周期读取 supplier_lifecycle_status（GET /admin/dict/data/supplier_lifecycle_status）；业务接口只传编码，不传中文标签或字典数据 ID。
• 接口文档冻结 API 与业务逻辑；本期物理表统一使用详细设计冻结的 supplier_*，不增加 resource_ 前缀。Entity、Mapper、DDL 和索引仍须在新任务 worktree 中核对当前 migration 与实际 schema。

1. 范围与事实依据

严格收敛规则

1. 路径、方法、平台权限码、状态、审批语义以详细设计 v3.0 为准。
2. 字段上限以本文件“共享 DTO / VO 字典”的冻结值为准，并与最新详细设计的字段修订保持一致；不得再回退到历史较小值。
3. 审批完整快照、幂等、防乱序、可靠事件采用 v3.0 的更严格增量。
4. 账号掩码不落库；物理表前缀统一为详细设计冻结的 supplier_*。对外契约锁定“永不返回完整账号”。
5. 本文件未定义的枚举、缓存和降级语义不得自行补造；供应商错误码已冻结为资源服务共享段中的 395xxx 子段。

本期不做

• 批量导入、导入批次、导入明细、失败清单和失败重导；本期同时不建导入表、不生成 Entity/Mapper/DTO/Controller/Service/Job、空实现或假成功。
• 履约评价自动采集与信用等级自动聚合。
• 本地审批流、审批按钮、审批待办。
• 供应商域中的应付、付款、团核算、余额和付款金额算法。
• 任何前端源码或资源修改。

1.1 后端代码生成冻结规则

OpenAPI 3.0 机器契约

仅导出本期 16 个 HTTP operation。所有 operation 都带 x-hl-access、x-hl-permissions、x-hl-rules、x-hl-errors 和原始请求/响应契约，供代码生成器同时生成结构与强制业务策略；不能只读取 path 而忽略扩展字段。管理端菜单和按钮由平台配置，服务端统一调用现有 UserFeignClient.hasPermission 校验权限码且异常失败关闭，不再生成固定角色判断。

正在生成内嵌契约…

正在生成…

生成准入门禁

1. 先在新任务 worktree 中重新核对分支、工作区、Supplier 所属 migration/实际 schema，以及现有外部运行条件；外部条件不满足时只关闭对应 Port，不修改其他模块。
2. Supplier 业务代码已按关联工单完成独立审计与 TEST 验收；Gateway 必须另开后端任务补充 /admin/supplier/** 路由并运行路由审计。企微适配器模仿系统现有调用接口，Supplier 模板/controlId 未完成配置与实证时保持关闭，且不得标记“跨模块联调完成”。
3. 只生成本期 operation；每个写接口必须实现可信身份、服务端授权、状态 Guard、锁/幂等、事务、审计和失败零副作用。
4. 错误码使用本文件的逐项冻结值：395001～395039；实现后由 ErrorCodeRegistry 做范围与重复 FAIL-FAST 校验。
5. 跨服务写只能沿用本地事务 + 可靠事件/对账；不得同步直写其他 schema。
6. 生成结果必须补齐成功、未认证、越权、缺参、边界、非法状态、重复/乱序/超时与副作用测试后，才能称“实现完成”。

2. 通用接口契约

统一成功包络

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {}
}

写接口统一执行顺序

1. 可信身份、平台菜单/按钮权限、数据范围校验。
2. 目标存在性、归属、软删除和当前状态校验。
3. expectedUpdateTime、唯一性、业务字段和敏感字段校验。
4. 管理端写接口进入 @Idempotent 短窗防重；锁内继续执行状态、CAS 与唯一约束校验。
5. 本地事务写业务数据、变更日志和待发布事件。
6. 事务提交后才调用已启用的 Supplier 出站 Port；结果不确定时进入对账，不重复发起。DOMAIN_EVENT Publisher Port 未独立接入时保持关闭。

2.1 前端字典使用约定

查询方式

1. 供应商类型按需调用 GET /admin/dict/data/supplier_type。
2. 供应商生命周期按需调用 GET /admin/dict/data/supplier_lifecycle_status。
3. 两个接口均经 Gateway 访问并需要管理员认证；返回的 data 只包含启用项，并按 sortOrder ASC、dictDataId ASC 排序，页面无需再次按中文排序。

// GET /admin/dict/data/supplier_lifecycle_status
{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": [
    { "dictType": "supplier_lifecycle_status", "dictLabel": "草稿", "dictValue": "DRAFT", "sortOrder": 10, "status": "ACTIVE" },
    { "dictType": "supplier_lifecycle_status", "dictLabel": "注册审核中", "dictValue": "VETTING", "sortOrder": 20, "status": "ACTIVE" },
    { "dictType": "supplier_lifecycle_status", "dictLabel": "合作中", "dictValue": "ACTIVE", "sortOrder": 30, "status": "ACTIVE" }
  ]
}

组件映射规则

const options = dictData.map(item => ({
  label: item.dictLabel,
  value: item.dictValue
}))

// 展示：用业务响应中的 code 匹配 dictValue，再显示 dictLabel
// 提交：只提交 value（例如 ACTIVE / HOTEL），不得提交中文、dictDataId 或整条字典对象

• 类型字段：创建、更新和提交注册表单只发送 types: [{ typeCode: "HOTEL" }]；请求不接收 typeName。列表和详情响应中的 typeName 是服务端显示快照，不能作为业务判断依据。
• 生命周期字段：列表筛选提交 status 编码；状态变更按钮仍必须按第 4 节状态机收窄合法目标，不能把 7 个字典项全部当作可跳转状态。
• 资源模块：resourceModule 不是 supplier_type 字典；固定为 SCENIC、RESTAURANT、SUPPLIES、SUPPLIES_COMBO、ACTIVITY、HOTEL、SERVICE、COST_ITEM、STAFF、VEHICLE，VEHICLE 的菜单原文为“车队管理-车队管理”。FLEET 仍可作为供应商类型/资格编码，但供应商侧不新增车队或挂接车辆。
• 同名状态：字典接口数据项自身的 status=ACTIVE 表示“该字典项启用”，不是供应商处于合作中；供应商生命周期必须读取该项的 dictValue。
• 未知编码：未匹配到字典时显示原始编码并上报契约异常，不得显示错误中文或静默改写业务值。
• 缓存更新：沿用平台现有字典缓存刷新机制；字典管理修改后不得另维护供应商页面私有枚举副本。

当前启用值（2026-08-21）

上表用于契约审阅和回归测试；运行时选项仍以字典接口返回的启用项为准。业务状态机和服务端枚举校验不因字典标签修改而改变。

3. 权限与字段可见性

4. 状态机与可用性

供应商七态总流程图

“状态内操作”不是新状态；只有“合法目标状态”列表示状态变化。任何未在详细设计状态图中的迁移均拒绝。

5. 接口目录与统一契约卡片

6. 共享 DTO / VO 字典

SupplierDraftUpsertRequest

嵌套输入

供应商响应

类型、资质、联系人

账户与审批

其余严格命令 DTO

完整返回 VO 补充

7. 业务错误码（代码生成冻结）

8. 需求—接口追踪

9. 双来源一致性与内部实现边界

10. 验收矩阵